home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audiofile / AFwriteframes.z / AFwriteframes
Encoding:
Text File  |  1998-10-20  |  8.4 KB  |  133 lines
  1.  
  2.  
  3.  
  4. aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))                                          aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      afWriteFrames - write audio sample frames to a specified track in an
  10.      audio file
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiiooooffffiiiilllleeee....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((ccccoooonnnnsssstttt AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee ffffiiiilllleeee,,,, iiiinnnntttt ttttrrrraaaacccckkkk,,,,
  16.                        vvvvooooiiiidddd ****ssssaaaammmmpppplllleeeessss,,,, ccccoooonnnnsssstttt iiiinnnntttt ccccoooouuuunnnntttt))))
  17.  
  18. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  19.      _f_i_l_e      expects the AAAAFFFFffffiiiilllleeeehhhhaaaannnnddddlllleeee structure for the audio file to which
  20.                audio sample data will be written.  This structure is usually
  21.                the returned value of a call to aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm).
  22.  
  23.      _t_r_a_c_k     is an integer which identifies the audio track (chunk) in the
  24.                file to be accessed.  Since all currently supported file
  25.                formats allow at most one audio track per file, the value
  26.                AAAAFFFF____DDDDEEEEFFFFAAAAUUUULLLLTTTT____TTTTRRRRAAAACCCCKKKK should always be used for this argument for
  27.                now.
  28.  
  29.      _s_a_m_p_l_e_s   is a pointer to a buffer containing samples to be written to
  30.                the audio file.
  31.  
  32.      _c_o_u_n_t     expects the number of sample _f_r_a_m_e_s you want to write to the
  33.                audio track.  For a stereo track, a sample frame would consist
  34.                of a <left, right> sample pair.  For a monaural track, a sample
  35.                frame would be a single sample.
  36.  
  37. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  38.      aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) returns the number of sample frames written to the
  39.      internal track.  The return value normally is greater than or equal to 0.
  40.      In the event of an error, aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) will return -1, and the error
  41.      value can be retrieved via oooosssseeeerrrrrrrroooorrrr(3C).
  42.  
  43. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  44.      aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) writes data to the specified track of an audio file from
  45.      the _s_a_m_p_l_e_s buffer.
  46.  
  47.      aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) attempts to write _c_o_u_n_t sample frames from the _s_a_m_p_l_e_s
  48.      buffer to the track, starting at the current location of the file write
  49.      pointer within the track. _s_a_m_p_l_e_s should be of type ssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr****,
  50.      uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr****, sssshhhhoooorrrrtttt****, iiiinnnntttt****, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt****, ffffllllooooaaaatttt****, or ddddoooouuuubbbblllleeee**** depending
  51.      on the width and format of the samples in the audio track as set using
  52.      aaaaffffIIIInnnniiiittttSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm).
  53.  
  54.      When an audio file is opened with write access by aaaaffffOOOOppppeeeennnnFFFFiiiilllleeee(3dm) or
  55.      aaaaffffOOOOppppeeeennnnFFFFDDDD(3dm), the logical write pointer for the audio data is
  56.      initialized to point to the location of the first sample frame in the
  57.      track.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))                                          aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      Before returning, aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) automatically updates the logical write
  75.      pointer for _t_r_a_c_k so that it points to the location of the sample frame
  76.      following the last one written to the file.
  77.  
  78.      The _s_a_m_p_l_e_s buffer is interpreted differently depending on the current
  79.      configuration of the audio track.  In particular, the sampwidth parameter
  80.      may or may not be meaningful, depending on what the sampfmt parameter is.
  81.      See aaaaffffGGGGeeeettttSSSSaaaammmmpppplllleeeeFFFFoooorrrrmmmmaaaatttt(3dm) for a full explanation of sample
  82.      representations.
  83.  
  84.      aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) automatically compresses data for audio tracks which are
  85.      encoded using the CCITT G.722, CCITT G.711, MPEG, and Aware
  86.      MultiRate/Lossless algorithms.  The data is passed to aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((())))
  87.      from an application program in the standard two's complement linear PCM
  88.      format, but this is by no means guaranteed for later compression types
  89.      (see aaaaffffGGGGeeeettttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnn(3dm) for more information about this).  You select
  90.      a compression scheme for an audio track by calling
  91.      aaaaffffIIIInnnniiiittttCCCCoooommmmpppprrrreeeessssssssiiiioooonnnn(3dm).  To achieve real-time G.722 compression, the
  92.      application process may require non-degrading scheduling priority (see
  93.      sssscccchhhheeeeddddccccttttllll(2) or nnnnpppprrrriiii(1))
  94.  
  95.      If an audio track contains data for more than a single audio channel, the
  96.      data placed in the _s_a_m_p_l_e_s buffer should be interleaved. Sample data to
  97.      be written to a stereo file should be buffered as a sequence of
  98.      left/right pairs (sample "frames").  Interleave conventions for files
  99.      containing  multichannel audio data are described in the AIFF-C
  100.      specification.
  101.  
  102. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  103.      Example: to write 10000 stereo 16-bit sample pairs to a stereo AIFF-C
  104.      file, place 20000 individual samples (i.e., 10000 <left, right> sample
  105.      pairs) into a sssshhhhoooorrrrtttt[[[[]]]] buffer, and pass the buffer to aaaaffffWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss(((()))) with
  106.      _c_o_u_n_t set to 10000.
  107.  
  108. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  109.      This routine will not function correctly if the user changes the file
  110.      position on the file descriptor for the AFfilehandle being manipulated.
  111.      See the section _C_A_V_E_A_T_S _F_O_R _U_S_I_N_G _T_H_E _H_A_N_D_L_E'_S _F_I_L_E _D_E_S_C_R_I_P_T_O_R in
  112.      aaaaffffIIIInnnnttttrrrroooo(3dm) for some important information about how to deal with this
  113.      situation.
  114.  
  115. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  116.      afOpenFile(3dm), afSeekFrame(3dm), afInitSampleFormat(3dm)
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.